<!-------- @HEADER
 !
 ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !
 !  Zoltan Toolkit for Load-balancing, Partitioning, Ordering and Coloring
 !                  Copyright 2012 Sandia Corporation
 !
 ! Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
 ! the U.S. Government retains certain rights in this software.
 !
 ! Redistribution and use in source and binary forms, with or without
 ! modification, are permitted provided that the following conditions are
 ! met:
 !
 ! 1. Redistributions of source code must retain the above copyright
 ! notice, this list of conditions and the following disclaimer.
 !
 ! 2. Redistributions in binary form must reproduce the above copyright
 ! notice, this list of conditions and the following disclaimer in the
 ! documentation and/or other materials provided with the distribution.
 !
 ! 3. Neither the name of the Corporation nor the names of the
 ! contributors may be used to endorse or promote products derived from
 ! this software without specific prior written permission.
 !
 ! THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
 ! EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 ! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 ! PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
 ! CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 ! EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 ! PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 ! PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 ! LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 ! NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 ! SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 !
 ! Questions? Contact Karen Devine	kddevin@sandia.gov
 !                    Erik Boman	egboman@sandia.gov
 !
 ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !
 ! @HEADER
-------> 
<HTML>
<HEAD>
   <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
   <META NAME="GENERATOR" CONTENT="Mozilla/4.04 [en] (X11; U; SunOS 4.1.3_U1 sun4m) [Netscape]">
  <meta name="sandia.approval_type" content="formal">
  <meta name="sandia.approved" content="SAND2007-4748W">
  <meta name="author" content="Zoltan PI">


   <TITLE>Zoltan User's Guide:  C++ Interface</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">

<div ALIGN=right><b><i><a href="ug.html">Zoltan User's Guide</a>&nbsp; |&nbsp; <a href="ug_fortran.html">Next</a>&nbsp; |&nbsp; <a href="ug_usage.html">Previous</a></i></b></div>


<H2>
<A NAME="cpp ug"></A>C++ Interface</H2>
The C++ interface to the Zoltan library is contained in the header files
listed below.  
Each header file defines one class.  Each class represents a Zoltan
data structure and the functions that operate on that data structure.
The class methods in the header files call functions in the Zoltan C library.
So to use the C++ interface from your application, include
the appropriate header file and link with the Zoltan C library.

<P><TABLE rules=cols,rows frame=box align=center cellpadding=5>
<TR> <TH>header file</TH> <TH>class</TH></TR>
<TR> <TD><I>include/zoltan_cpp.h</I></TD>
     <TD><B>Zoltan</B>, representing a 
     <a href="ug_interface_init.html">load balancing</a> instance</TD>
<TR> <TD><I>Utilities/Communication/zoltan_comm_cpp.h</I></TD>
     <TD><B>Zoltan_Comm</B>, representing an 
     <a href="ug_util_comm.html">unstructured communication</a> instance </TD>
</TR>
<TR> <TD><I>Utilities/DDirectory/zoltan_dd_cpp.h</I></TD>
     <TD><B>Zoltan_DD</B>, representing a 
     <a href="ug_util_dd.html">distributed directory</a> instance </TD>
</TR>
<TR> <TD><I>Utilities/Timer/zoltan_timer_cpp.h</I></TD>
     <TD><B>Zoltan_Timer</B>, representing a timer instance </TD>
</TR>
</TABLE>
<p>
More detailed information about the interface may be found in the
<a href="../dev_html/dev_cpp.html">Zoltan Developer's Guide</a>.
<p>
Simple examples of the use of the interface may be found in the
<I>examples/CPP</I> directory.  A more complete example is the 
test driver <a href="../dev_html/dev_driver.html">zCPPdrive</a>.  The
source code for this test driver is in the <I>driver</I> directory.

<p>
A note on declaring application registered query functions from a
C++ application may be found in the section titled
<a href="ug_query.html">Application-Registered Query Functions</a>.
<p>
Two peculiarities of the wrapping of Zoltan with C++ classes are
mentioned here:
<ol>
<li>
You must call the C language function
<a href="ug_interface_init.html#Zoltan_Initialize"><I>Zoltan_Initialize</I> </a>
before using the C++ interface to the Zoltan library.  This function should only
be called once.  Due to design choices,
the C++ interface maintains no global state that is
independent of any instantiated objects, so it does not know if the
function has been called or not.  Therefore, the C++ wrappers do not call 
<a href="ug_interface_init.html#Zoltan_Initialize"><I>Zoltan_Initialize</I> </a>
for you.
<li>
It is preferable to allocate <B>Zoltan</B> objects dynamically so you can
explicitly delete them before your application exits. 
(<B>Zoltan</B> objects allocated instead on the stack will be deleted 
automatically at the completion of the scope in which they were created.)
The reason is that the <B>Zoltan</B>
destructor calls Zoltan_Destroy(), which makes an MPI call to free
the communicator in use by the <B>Zoltan</B> object.  However the
MPI destructor may have been called before the <B>Zoltan</B>
destructor.  In this case you
would receive an error while your application is exiting.
</ol>
This second point is illustrated in the good and bad example below.
<p>

<CENTER><TABLE BORDER=2 COLS=1 WIDTH="90%" NOSAVE >
<TR>
<TD><A NAME="c++ item 1"></A>
<TT>int main(int argc, char *argv[])</tt><br>
<TT>{</tt><br>
<TT>&nbsp;MPI::Init(argc, argv);</tt><br>
<TT>&nbsp;int rank = MPI::COMM_WORLD.Get_rank();</tt><br>
<TT>&nbsp;int size = MPI::COMM_WORLD.Get_size();</tt><br><br>
<TT>&nbsp;//<I>Initialize the Zoltan library with a C language call</I></TT><br>
<TT>&nbsp;float version;</TT><br>
<TT>&nbsp;Zoltan_Initialize</A>(argc, argv, &version);</TT><br><br>
<TT>&nbsp;//<I>Dynamically create Zoltan object.</I></tt><br>
<TT>&nbsp;Zoltan *zz = new Zoltan(MPI::COMM_WORLD);</tt><br>
<TT>&nbsp;zz->Set_Param("LB_METHOD", "RCB");</tt><br><br> 
<TT>&nbsp;//<I>Several lines of code would follow, working with zz</I></tt><br><br>
<TT>&nbsp;//<I>Explicitly delete the Zoltan object</I></tt><br>
<TT>&nbsp;delete zz;</tt><br>
<TT>&nbsp;MPI::Finalize();</tt><br>
<TT>&nbsp;}</tt><br>
</TR>
<CAPTION ALIGN=BOTTOM><I>Good example, Zoltan object is dynamically allocated
and explicity deleted before exit.</I></CAPTION>
</TABLE></CENTER>
<br>
<br>

<CENTER><TABLE BORDER=2 COLS=1 WIDTH="90%" NOSAVE >
<TR>
<TD><A NAME="c++ item 2"></A>
<TT>int main(int argc, char *argv[])</tt><br>
<TT>{</tt><br>
<TT>Zoltan zz;</tt><br><br>
<TT>&nbsp;MPI::Init(argc, argv);</tt><br>
<TT>&nbsp;int rank = MPI::COMM_WORLD.Get_rank();</tt><br>
<TT>&nbsp;int size = MPI::COMM_WORLD.Get_size();</tt><br><br>
<TT>&nbsp;//<I>Initialize the Zoltan library with a C language call</I></TT><br>
<TT>&nbsp;float version;</TT><br>
<TT>&nbsp;Zoltan_Initialize</A>(argc, argv, &version);</TT><br><br>
<TT>&nbsp;zz.Set_Param("LB_METHOD", "RCB");</tt><br><br> 
<TT>&nbsp;//<I>Several lines of code would follow, working with zz</I></tt><br><br>
<TT>&nbsp;MPI::Finalize();</tt><br>
<TT>&nbsp;}</tt><br>
</TR>
<CAPTION ALIGN=BOTTOM><I>Bad example, the MPI destructor may execute before the
Zoltan destructor at process exit.</I></CAPTION>
</TABLE></CENTER>
<br>
<br>

<HR WIDTH="100%">[<A HREF="ug.html">Table of Contents</A>&nbsp; |&nbsp;
<A HREF="ug_fortran.html">Next:&nbsp;Fortran Interface</A>&nbsp;
|&nbsp; <A HREF="ug_usage.html">Previous:&nbsp;Zoltan Usage</A>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</BODY>
</HTML>
